docs(readme): add Win32 + classic COM section (JavaScript/TypeScript) - #70

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…HWND guidance

- Replace the hardcoded-version winmd download with a single block that
  auto-resolves the latest Microsoft.Windows.SDK.Win32Metadata version from
  nuget.org, downloads, and extracts to ./win32meta — no version to pick, no
  NuGet client. The generate example now references ./win32meta/Windows.Win32.winmd.
  Verified end-to-end (resolves 71.0.14-preview, extracts the 23 MB winmd).
- Fix now-incorrect handle guidance: classic-COM HWND projects as `bigint |
  number` (not `bigint | Buffer`). For Electron, read the value out of
  getNativeWindowHandle() (readBigUInt64LE(0)) — do not pass the Buffer itself.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The fetch and generate steps were two separate blocks, and the generate block
used bash `\` line-continuations that break when pasted into PowerShell on
Windows. Merge them into one PowerShell block that fetches the latest winmd and
runs `npx dynwinrt-codegen generate` in one paste — no editing, no version to
pick. Verified the fetch+generate flow end-to-end (produces ITaskbarList3.js/.d.ts).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…r / Mica)

Two research sub-agents (npm demand analysis + local generation verification)
independently converged: the most compelling Win32 example for Electron devs is
DWM window effects — the Windows 11 dark title bar / Mica / Acrylic look, which
has NO Electron/JS equivalent and uses the same HWND from getNativeWindowHandle().
Change the generate line to `--namespace Windows.Win32.Graphics.Dwm --class-name
Apis` and point out the other high-demand APIs (ITaskbarList3, Credential Manager
as a keytar replacement, Registry). Verified the exact block generates
`dwmSetWindowAttribute` end-to-end.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…atches generate line)

The generate line now showcases Windows.Win32.Graphics.Dwm, so align the flat
usage example with it: show `dwmSetWindowAttribute` enabling the Windows 11 dark
title bar (the "wow"), instead of the registry read. Keep the registry
`{ status, phkResult }` out-param pattern described in the prose so the flat
return-object contract is still taught. Verified the exact call at runtime —
dwmSetWindowAttribute(hwnd, 20, <4-byte BOOL Buffer>, 4) returns { status: 0x0 }.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

… honest swap note

Reverts the DWM experiment. Two problems with DWM as the headline example:
(a) the generate line generated DWM but the first usage section is ITaskbarList3
— incoherent; (b) most Electron apps are frameless (frame:false / custom title
bar), so DwmSetWindowAttribute(dark title bar) does nothing for them — it isn't
"what Electron devs need". Also, Electron already provides the flashy taskbar
features (setProgressBar/setOverlayIcon/setThumbarButtons), powerSaveBlocker,
flashFrame, globalShortcut, setJumpList.

Restore the coherent original: generate ITaskbarList3 (used in the very next
section) and keep the clean Registry flat example. The swap note now points at
the genuine gaps Electron does NOT cover — Windows Credential Manager (a keytar
replacement safeStorage doesn't provide) and arbitrary registry access.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…y Apis)

Per feedback that generating one class at a time is the uncommon case: the
generate example now generates the whole Windows.Win32.System.Registry flat API
(--class-name Apis = the namespace's [DllImport] bundle), which is what the Flat
Win32 example below actually imports. Prose explains Apis (namespace bundle) vs
naming a specific classic-COM interface (ITaskbarList3). Verified: namespace-only
(no --class-name) does NOT emit flat functions — --class-name Apis is required.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…fy interop vs classic COM

Reading-flow fixes:
- The headline "Getting Windows.Win32.winmd" copy-paste block now generates
  ITaskbarList3 (the FIRST usage example), instead of the Registry flat API that
  only appears third. Verified the command emits ITaskbarList3.js + TBPFLAG.js.
- The Flat Win32 (Registry) example now re-shows its own generate command inline
  (--class-name Apis, namespace-level flat). Verified it emits Apis.js
  (regOpenKeyExW/regCloseKey) + REG_SAM_FLAGS.js.
- Reworded the --class-name explainer to cover both cases (specific interface vs
  the synthetic Apis namespace bundle).

Clarity fix (Q1): the Classic COM and WinRT-interop examples looked identical from
the code. Added a one-line contrast: ITaskbarList3 is a pure classic-COM object
(calls stay on its vtable), whereas an interop interface is a one-way bridge that
hands back a live WinRT object (DataTransferManager) from an HWND.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The examples read like C++/Win32 with an HWND bolted on; the audience is Electron
developers. Both HWND examples are now grounded in the Electron object model:
app.whenReady() → new BrowserWindow → win.getNativeWindowHandle().readBigUInt64LE(0),
so where the handle comes from is obvious and the snippet is copy-into-main.js ready.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Constructing `new BrowserWindow({ width: 900, height: 600 })` in the snippet
wrongly implied the window size mattered and that you make a new window just to
get its handle. Real apps already have their window — read the HWND off the
existing mainWindow (any size). Removes the confusion.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>